Target endpoints

A target is one number a campaign calls, together with the bot that takes the call and anything the bot should know before it starts talking. Targets belong to a campaign, so every endpoint here is addressed under one: the campaign must exist first.

There are two ways to add targets, and they behave differently:

Add targets posts JSON and appends. The targets already on the campaign remain, and you can add more at any time until the campaign has ended.
Import targets uploads a .csv file and replaces. Every target already on the campaign is erased.

Add targets

This endpoint adds one or more targets to a campaign, leaving existing targets unchanged.

Endpoint

POST /api/v1/campaignDialer/campaigns/{campaignID}/targets

Body

targets is an array of target objects:

Property	Type	Description	Error result
`targetNumber`	string	Required. URI of the number to call: `tel:+972541234567` or `sip:8508355@audiocodes.com`.	`Missing target number`, `Invalid target number format`
`callingNumber`	string	Required. Number shown to the person being called, or `Anonymous`.	`Missing calling number`, `Invalid calling number format`
`botName`	string	UUID of the bot that handles this call. Required unless the campaign has a `defaultBotName`, which this overrides.	`Invalid bot name`, `Missing bot name`
`tag`	string	A short label of your own, to help you find the target later. Default `""`.	—
`enabled`	boolean	Whether the target is called. Default `true`.	—
`botMetadata`	string	A JSON object, as an escaped string, passed to the bot when the call starts. Default `""`.	`Invalid Metadata`

The bot receives botMetadata in the dialoutMetadata field of the first message. See Manage targets.

Request

POST /api/v1/campaignDialer/campaigns/540e84e0f29b42d4a713446633441115/targets HTTP/1.1
Host: livehub.audiocodes.io
Content-Type: application/json;charset=UTF-8
Authorization: Bearer {token}

{
  "targets": [
    {
      "tag": "Morse 1st",
      "enabled": "true",
      "botName": "Nike Bot",
      "targetNumber": "tel:+972541234567",
      "callingNumber": "Anonymous",
      "botMetadata": "{\"field1\":\"val1\",\"field2\":\"val2\"}"
    }
  ]
}

Response

201 Created — one entry per target you sent, in the order you sent them. A target that failed validation carries the reason in result instead of Success, so check every entry: the request as a whole can succeed while individual targets are rejected.

{
  "targets": [
    {
      "result": "Success",
      "targetID": "540e8400-e29b-41d4-a713-446655441111"
    },
    {
      "result": "Success",
      "targetID": "540e8400-e29b-41d4-a713-446655441115"
    },
    {
      "result": "Invalid target number",
      "targetID": "N/A"
    },
    {
      "result": "Success",
      "targetID": "540e8400-e29b-41d4-a713-446655441114"
    },
    {
      "result": "Missing Bot",
      "targetID": "540e8400-e29b-41d4-a713-446655441118"
    }
  ]
}

400 Bad Request — no target was created.

{
  "error": {
    "message": "Targets creation failed. Add new targets - allowed all the time as long as campaign not ended."
  }
}

Import targets

This endpoint uploads a .csv file of targets. This is the practical way to load a long list.

Endpoint

POST /api/v1/campaignDialer/campaigns/{campaignID}/targetsFile

Importing replaces the target list: every target already on the campaign is erased. You can import freely while the campaign has not started; once it has, you can import only into a campaign that has no targets.

The file is comma delimited, with these columns in this order:

Tag,Enabled,Bot Name,Target Number,Calling Number,Bot Meta data

Tag,Enabled,Bot Name,Target Number,Calling Number,Bot Meta data
Morse 1st,TRUE,Nike Bot,sip:8508355@audiocodes.com,Anonymous,"{\"field1\": \"val1\", \"field2\": \"val2\"}"
Morse 2nd,TRUE,Nike Bot,tel:+972541234567,Anonymous,"{\"field1\": \"val1\", \"field2\": \"val2\"}"

Request

POST /api/v1/campaignDialer/campaigns/540e84e0f29b42d4a713446633441115/targetsFile HTTP/1.1
Host: livehub.audiocodes.io
Content-Type: text/csv
Content-Length: {length}
Authorization: Bearer {token}

Response

Code	Meaning
`201 Created`	The targets were created.
`400 Bad Request`	The targets were not created.

List targets

This endpoint lists the targets of a campaign with their settings and their current status.

Endpoint

GET /api/v1/campaignDialer/campaigns/{campaignID}/targets

Query parameters

Filtering, sorting and pagination follow the campaign query conventions, and apply equally to Export targets. The filterable fields are:

Parameter	Description	Example
`tag`	Targets carrying this tag.	`?tag=main_phone`
`status`	Targets in one status. See Get campaign and target status values.	`?status=Not%20initiated`
`botName`	Targets handled by this bot.	`?botName=bot4`
`targetNumber`	Targets whose number matches.	`?targetNumber=104`
`lastFailureReason`	Targets whose last attempt failed for this reason. See Get campaign and target status values.	`?lastFailureReason=target%20no%20answer`

Sorting accepts tag, status, botName, targetNumber or lastFailureReason as sortCol.

Request

GET /api/v1/campaignDialer/campaigns/demo123/targets?page=2&limit=5&sortCol=status&sortDir=asc&botName=bot4 HTTP/1.1
Host: livehub.audiocodes.io
Authorization: Bearer {token}

Response

200 OK — each target as a setting object holding what you configured and a status object holding what has happened to it, alongside the pagination properties.

{
  "targets": [
    {
      "targetID": "540e8400-e29b-41d4-a713-446655440000",
      "setting": {
        "tag": "Moshe Cohen 1st",
        "enabled": "True",
        "displayName": "Nike Bot",
        "botName": "c30e3335-2b5a-40ec-b7a8-613092b1eb1d",
        "targetNumber": "tel:+972541234567",
        "callingNumber": "Anonymous",
        "botMetadata": "{\"field1\":\"val1\",\"field2\":\"val2\"}"
      },
      "status": {
        "status": "Bot Failure",
        "lastFailureReason": "No Answer",
        "lastCallTime": "2023-08-21T14:30:15",
        "numOfReschedules": 10,
        "numOfRetries": 4,
        "BotResultMetaData": "{\"myParamName\":\"myParamValue\"}"
      }
    }
  ]
}

Bot result metadata

BotResultMetaData carries whatever the bot returned once the call ended. To populate it, set the bot's botOperationData parameter, either in the bot's configuration:

{
  "botOperationData": {
    "myParamName": "myParamValue"
  }
}

or dynamically, through sessionParams. For more information, refer to Specifying bot operation result.

Export targets

This endpoint downloads the targets of a campaign as a .csv file. It takes the same filtering, sorting and pagination parameters as List targets.

Endpoint

GET /api/v1/campaignDialer/campaigns/{campaignID}/targetsFile

Request

GET /api/v1/campaignDialer/campaigns/540e84e0f29b42d4a713446633441115/targetsFile HTTP/1.1
Host: livehub.audiocodes.io
Content-Type: text/csv
Authorization: Bearer {token}

Response

200 OK — the .csv file. It has more columns than the import format: alongside the settings, it carries the outcome of each target and the target's ID.

Tag,Enabled,Bot Display Name,Bot Name,Target Number,Calling Number,Bot Meta data,Status,Last Failure Reason,Last Call Time,Number Of Reschedules,Number Of Retries,Bot Result Meta Data,Target ID
Moshe1st,TRUE,Nike Bot,c30e3335-2b5a-40ec-b7a8-613092b1eb1d,sip:8508355@audiocodes.com,Anonymous,"{\"field1\": \"val1\", \"field2\": \"val2\"}",Dialer Success,N/A,2024-12-05T05:54:34,10,4,"{\"myParamName\":\"myParamValue\"}",540e8400-e29b-41d4-a713-446655440000
Moshe2nd,TRUE,Nike Bot,c30e3335-2b5a-40ec-b7a8-613092b1eb1d,tel:+972541234567,Anonymous,"{\"field1\": \"val1\", \"field2\": \"val2\"}",Not Initiated,,,,,,540e8400-e29b-41d4-a713-446655441111

500 Internal Server Error — the campaign has no targets.

Update targets

This endpoint changes existing targets. Each entry must name the targetID you are changing, which you get from Add targets or List targets.

Endpoint

PATCH /api/v1/campaignDialer/campaigns/{campaignID}/targets

What you can change depends on how far the campaign has progressed:

Before it starts, you can change every property of a target.
Once it has started, everything except enabled is discarded. You can still enable and disable a target, as long as it has not been processed yet, meaning its status is still Not initiated. This is how you take a number out of a running campaign without losing its history.

Request

PATCH /api/v1/campaignDialer/campaigns/540e84e0f29b42d4a713446633441115/targets HTTP/1.1
Host: livehub.audiocodes.io
Content-Type: application/json;charset=UTF-8
Authorization: Bearer {token}

{
  "targets": [
    {
      "targetID": "540e8400-e29b-41d4-a713-446655441111",
      "tag": "Moshe Cohen 1st",
      "enabled": "False",
      "botName": "47597ebb-1791-47f5-9c0b-2d8801d8beea",
      "botDisplayName": "new Bot",
      "callingNumber": "Anonymous",
      "targetNumber": "tel:+97230000000",
      "botMetadata": "{\"field1\":\"newVal1\",\"field2\":\"val2\"}"
    },
    {
      "targetID": "540e8400-e29b-41d4-a713-446655441115",
      "enabled": "False"
    }
  ]
}

Response

200 OK — one entry per target you sent, whether all of them succeeded or only some.

{
  "targets": [
    {
      "result": "success",
      "targetID": "540e8400-e29b-41d4-a713-446655441111"
    },
    {
      "result": "wrong Target ID",
      "targetID": "446655441115"
    }
  ]
}

400 Bad Request — every target failed.